$e.add Function
Syntax
Arguments
- eleobject|string|array
An HTML element, an ID or NAME, or an array of HTML elements, IDs, and/or NAMEs
- typestring
The event's type. These events are standard DOM events (minus the "on"), like 'click', 'mousedown', 'mouseup', 'keydown', 'blur' etc. Possible values are:
- click
When the user clicks on an element.
- dblclick
When the user double clicks on an element.
- mousedown
When the user presses the mouse down on an element.
- mouseup
When the user releases the mouse button after pressing mouse down on an element.
- mouseover
When the mouse cursor moves over an element.
- mousemove
When the mouse cursor is being moved over an element.
- mouseout
When the mouse cursor leaves an element.
- keypress
When the user presses a key. Will fire repeatedly while the key is being pressed.
- keydown
When the user presses a key. Fires on the key down.
- keyup
When the user presses a key and then releases it.
- focus
When the user gives focus to an element.
- blur
When a user 'blurs' an element. I.e. when an element looses focus.
- change
When the user makes a change in a form element.
- reset
When the user resets the data in a form using a 'Reset' button.
- submit
When the user clicks a form's 'Submit' button.
- scroll
When the user scrolls a scrollable element. This could be the page itself, of a DIV that has scroll bars.
- resize
When the user resizes the browser window.
- load
When the page is loaded.
- unload
When the page is unloaded (i.e. when you navigate to another page, or the browser is closed).
- eventHandlerfunction(e, scope)
The Javascript function you would liked to have called when the event occurs. The function will have access to the following parameters:
- eobject
The DOM event object. See The DOM 'Event' Object below.
- scopeobject
The scope object (see scope below.)
- scopeobject
An object scope to be passed into the function that handles the event. The scope object is passed in as the second parameter to the event handler function (the DOM event object is passed in as the first parameter).
This is an advanced parameter.- scopeOverridelogical
A true/false value for whether or not you would like the passed in scope to take the place of the HTML element in the "this." namespace.
This is an advanced parameter.- groupNamestring
A group name for the event. Can be used with $e.removeGroup() function to remove multiple events from multiple objects.
Your page might contain elements that have had events bound to them using the $e.add() function. If any of these elements are subsequently removed from the page (through setting innerHTML of a parent element, or through DOM manipulation), it is important to remove the events from these elements, or else a memory leak might occur.
Description
Add one or more event listeners to an HTML element.
Discussion
The $e.add() function allows you to add an event to a single or multiple HTML elements. You can call the $e.add() function multiple times for a given element and event, allowing you to add multiple event handlers for the same event. For example:
$e.add('firstname','blur',validate1);
$e.add('firstname','blur',validate2);When the 'firstname' element loses focus, the validate2() function will be called first (since it was the most recent event handler to be added), and then the validate1() function will be called next.
The DOM 'Event' Object
When a DOM event (such as 'blur', 'keypress' etc.) occurs, the browser automatically stores relevant information about the event (such as what key was pressed, what is the mouse position, etc.) in the DOM event object. This object is automatically passed in as the first parameter to the Javascript function that is handling the event.
The DOM event object can also be used to stop an event from 'bubbling' (i.e. a 'click' event on a button that was contained in a DIV will first cause the button's onclick event to fire, then will cause the DIVs onclick event to fire and the will cause the page's onclick event to fire). You might want to prevent the event from bubbling up to the DIV and the page. You can do this by using the $e.stopEvent() function, passing in the DOM event object to this function.
Example 1
Assume you have the following HTML page. Notice that the HTML has two input controls ('id_fn' and 'id_ln') and that there are no Javascript events defined in the HTML.
We want to add a handler for the 'onblur' event for both of these controls. When either of the controls looses focus, we want to call the blurred() function.
Notice that in the definition of the blurred() function, we show a parameter that is passed in (function blurred(e)). The argument is the DOM Event object that is automatically passed in to the event handler. The DOM Event object has information about the event that triggered the function call.
<html>
<head>
</head>
<body>
<input id="id_fn" name="firstname"/>
<input id="id_ln" name="lastname"/>
</body>
</html><script type="text/Javascript" src="Javascript/core.js"></script>
<script type="text/Javascript">
function blurred(e) {
alert('ID:' + this.id + '\n Event type: ' +e.type + '\n Value in control: ' + this.value);
}
/*Add the event handler for the 'blur' event to the 'id_fn' and 'id_ln' elements.*/
$e.add(['id_fn','id_ln'],'blur',blurred);
</script>Example 2
This example demonstrates how you can bind multiple event handlers to an event, and shows the order in which the event handlers are executed.
In this example, the HTML contains a definition for the onblur event for the 'id_fn' element. In addition to the event handler defined in the HTML, the Javascript code binds the msg2() function and then the msg3() function to the blur event for 'id_fn'.
If you load this page in a browser, when focus leaves the 'id_fn' element you will notice the following:
First, a dialog showing 'msg1' is shown, indicating that the event handler defined in the HTML executes first
Next, a dialog showing 'msg3' is shown, indicating that the most recent event handler added using $e.add() is executed next.
Finally, a dialog showing the control ID is shown, indicating that t he events added by $e.add() are executed in a 'last in - first out' order.
Notice that in the definition of the msg2() function we pass in the DOM event object and so the message box can display e.type (the type of the event that caused the event handler to be invoked). Also notice that the 'this' alias is implicitly passed in and can be used to get information about the control (such as it's ID - 'this.id', or current value - 'this.value')
<html>
<head>
</head>
<body>
<input id="id_fn" name="firstname" onblur="alert('msg1'); return false;" />
<input id="id_ln" name="lastname"/>
</body>
</html>
<script type="text/Javascript" src="Javascript/core.js"></script>
<script type="text/Javascript">
function msg2(e) {
alert('ID:' + this.id + '\n Event type: ' +e.type + '\n Value in control: ' + this.value);
}
function msg3(e) {
alert('msg3');
}
/*Bind the msg2() function call to the 'blur' event on the 'id_fn' and 'id_ln' elements.*/
$e.add(['id_fn','id_ln'],'blur',msg2);
$e.add('id_fn','blur',msg3);
</script>See Also